<!DOCTYPE html>
<html>
<head>
	<!-- Global site tag (gtag.js) - Google Analytics -->
	<script async src="https://www.googletagmanager.com/gtag/js?id='UA-133422980-2"></script>
	<script>
	  window.dataLayer = window.dataLayer || [];
	  function gtag(){dataLayer.push(arguments);}
	  gtag('js', new Date());

	  gtag('config', 'UA-133422980-2');
	</script>

	<meta charset="utf-8">
	<meta http-equiv="x-ua-compatible" content="ie=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">

	<title>
		gem5: Coding Style 
	</title>

	<!-- SITE FAVICON -->
	<link rel="shortcut icon" type="image/gif" href="/assets/img/gem5ColorVert.gif"/>

	<link rel="canonical" href="http://localhost:4000/documentation/general_docs/development/coding_style/">
	<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,300,700,800,600' rel='stylesheet' type='text/css'>
	<link href='https://fonts.googleapis.com/css?family=Muli:400,300' rel='stylesheet' type='text/css'>

	<!-- FAVICON -->
	<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

	<!-- BOOTSTRAP -->
	<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">

	<!-- CUSTOM CSS -->
	<link rel="stylesheet" href="/css/main.css">
</head>


<body>
	<nav class="navbar navbar-expand-md navbar-light bg-light">
  <a class="navbar-brand" href="/">
		<img src="/assets/img/gem5ColorLong.gif" alt="gem5" height=55px>
	</a>
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
  </button>
  <div class="collapse navbar-collapse" id="navbarNavDropdown">
    <!-- LIST FOR NAVBAR -->
    <ul class="navbar-nav ml-auto">
      <!-- HOME -->
      <li class="nav-item ">
        <a class="nav-link" href="/">Home</a>
      </li>

      <!-- ABOUT -->
			<li class="nav-item dropdown ">
				<a class="nav-link dropdown-toggle" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					About
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
          <a class="dropdown-item" href="/about">About gem5</a>
          <a class="dropdown-item" href="/publications">Publications</a>
          <a class="dropdown-item" href="/governance">Governance</a>
				</div>
			</li>

      <!-- DOCUMENTATION -->
			<li class="nav-item dropdown active">
				<a class="nav-link dropdown-toggle" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					Documentation
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
					<!-- Pull navigation from _data/documentation.yml -->
					
            <a class="dropdown-item" href="/documentation">gem5 documentation</a>
					
            <a class="dropdown-item" href="/documentation/learning_gem5/introduction">Learning gem5</a>
					
            <a class="dropdown-item" href="http://doxygen.gem5.org/release/current/index.html">gem5 Doxygen</a>
					
            <a class="dropdown-item" href="/documentation/reporting_problems">Reporting Problems</a>
					
				</div>
			</li>

      <!-- EVENTS -->
			<li class="nav-item dropdown ">
        <a class="nav-link" href="/events/">Events</a>
			</li>

      <!-- CONTRIBUTING -->
      <li class="nav-item ">
        <a class="nav-link" href="/contributing">Contributing</a>
      </li>

      <!-- BLOG -->
      <li class="nav-item ">
        <a class="nav-link" href="/blog">Blog</a>
      </li>

      <!-- SEARCH -->
			<li class="nav-item ">
        <a class="nav-link" href="/search">Search</a>
      </li>
    </ul>
  </div>
</nav>

	<main>
		<div class="sidenav-top">
  <div class="sidenav-brand bg-light">
    <a href="/"><img src="/assets/img/gem5ColorLong.gif" height="55px"></a>
  </div>
  <div class="search">
    <form action="/search" method="get">
      <!-- <label for="search-box"><i class="fa fa-search"></i></label> -->
      <input type="text" name="query">
      <button type="submit" name="submit"><i class="fa fa-search"></i></button>
    </form>
  </div>
</div>
<div class="sidenav">
  <!-- Pull navigation from _data/documentation.yml -->
  
    
    
      <a class="item" href="/documentation" role="button" aria-expanded="false" aria-controls="collapseExample">
        gem5 documentation
      </a>
      <div class="collapse " id="gem5_documentation">
        
      </div>
    
      <a class="item" href="/documentation/general_docs/development/coding_style/" role="button" aria-expanded="false" aria-controls="collapseExample">
        Code Style
      </a>
      <div class="collapse " id="code_style">
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#building" role="button" aria-expanded="false" aria-controls="collapseExample">
        Building
      </a>
      <div class="collapse " id="building">
        
          <a class="subitem " href="/documentation/general_docs/building">Building</a>
        
          <a class="subitem " href="/documentation/general_docs/building/EXTRAS">Building EXTRAS</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#doxygen-docs" role="button" aria-expanded="false" aria-controls="collapseExample">
        Doxygen
      </a>
      <div class="collapse " id="doxygen-docs">
        
          <a class="subitem " href="http://doxygen.gem5.org/develop/index.html">Develop Branch</a>
        
          <a class="subitem " href="http://doxygen.gem5.org/release/v19-0-0-0/index.html">v19.0.0.0</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#fullsystem" role="button" aria-expanded="false" aria-controls="collapseExample">
        Full System
      </a>
      <div class="collapse " id="fullsystem">
        
          <a class="subitem " href="/documentation/general_docs/fullsystem/disks">Creating Disk Images</a>
        
          <a class="subitem " href="/documentation/general_docs/fullsystem/devices">Devices</a>
        
          <a class="subitem " href="/documentation/general_docs/fullsystem/m5term">m5term</a>
        
          <a class="subitem " href="/documentation/general_docs/fullsystem/building_arm_kernel">Building Linux ARM Kernel</a>
        
          <a class="subitem " href="/documentation/general_docs/fullsystem/building_android_m">Building Android Marshmallow</a>
        
          <a class="subitem " href="/documentation/general_docs/fullsystem/guest_binaries">Guest binaries</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#memory_system" role="button" aria-expanded="false" aria-controls="collapseExample">
        Memory System
      </a>
      <div class="collapse " id="memory_system">
        
          <a class="subitem " href="/documentation/general_docs/memory_system/">Memory System</a>
        
          <a class="subitem " href="/documentation/general_docs/memory_system/gem5_memory_system">gem5 Memory System</a>
        
          <a class="subitem " href="/documentation/general_docs/memory_system/replacement_policies">Replacement Policies</a>
        
          <a class="subitem " href="/documentation/general_docs/memory_system/indexing_policies">Indexing Policies</a>
        
          <a class="subitem " href="/documentation/general_docs/memory_system/classic-coherence-protocol">Classic memory system coherence</a>
        
          <a class="subitem " href="/documentation/general_docs/memory_system/classic_caches">Classic caches</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#ruby" role="button" aria-expanded="false" aria-controls="collapseExample">
        Ruby Memory System
      </a>
      <div class="collapse " id="ruby">
        
          <a class="subitem " href="/documentation/general_docs/ruby">Ruby</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/cache-coherence-protocols">Cache Coherence Protocols</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/garnet-2">Garnet 2.0</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/MOESI_CMP_directory">MOESI CMP directory</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/garnet_synthetic_traffic">Garnet Synthetic Traffic</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/slicc">SLICC</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/MI_example">MI example</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/Garnet_standalone">Garnet standalone</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/interconnection-network">Interconnection network</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/MOESI_hammer">MOESI hammer</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/MOESI_CMP_token">MOESI CMP token</a>
        
          <a class="subitem " href="/documentation/general_docs/ruby/MESI_Two_Level">MESI two level</a>
        
          <a class="subitem " href="/documentation/general_docs/memory_system/replacement_policies">Replacement Policies</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#cpu_models" role="button" aria-expanded="false" aria-controls="collapseExample">
        CPU Models
      </a>
      <div class="collapse " id="cpu_models">
        
          <a class="subitem " href="/documentation/general_docs/cpu_models/SimpleCPU">SimpleCPU</a>
        
          <a class="subitem " href="/documentation/general_docs/cpu_models/O3CPU">O3CPU</a>
        
          <a class="subitem " href="/documentation/general_docs/cpu_models/TraceCPU">TraceCPU</a>
        
          <a class="subitem " href="/documentation/general_docs/cpu_models/minor_cpu">Minor CPU Model</a>
        
          <a class="subitem " href="/documentation/general_docs/cpu_models/execution_basics">Execution Basics</a>
        
          <a class="subitem " href="/documentation/general_docs/cpu_models/visualization">Visualization</a>
        
      </div>
    
      <a class="item" href="/documentation/general_docs/m5ops" role="button" aria-expanded="false" aria-controls="collapseExample">
        M5ops
      </a>
      <div class="collapse " id="m5ops">
        
      </div>
    
      <a class="item" href="/documentation/general_docs/checkpoints" role="button" aria-expanded="false" aria-controls="collapseExample">
        Checkpoints
      </a>
      <div class="collapse " id="checkpoints">
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#directed_testers" role="button" aria-expanded="false" aria-controls="collapseExample">
        Directed Testers
      </a>
      <div class="collapse " id="directed_testers">
        
          <a class="subitem " href="/documentation/general_docs/debugging_and_testing/directed_testers/garnet_synthetic_traffic">Garnet Synthetic Traffic</a>
        
          <a class="subitem " href="/documentation/general_docs/debugging_and_testing/directed_testers/ruby_random_tester">Ruby Random Tester</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#debugging" role="button" aria-expanded="false" aria-controls="collapseExample">
        Debugging
      </a>
      <div class="collapse " id="debugging">
        
          <a class="subitem " href="/documentation/general_docs/debugging_and_testing/debugging/trace_based_debugging">Trace-based Debugging</a>
        
          <a class="subitem " href="/documentation/general_docs/debugging_and_testing/debugging/debugger_based_debugging">Debugger-based Debugging</a>
        
          <a class="subitem " href="/documentation/general_docs/debugging_and_testing/debugging/debugging_simulated_code">Debugging Simulated Code</a>
        
          <a class="subitem " href="/documentation/reporting_problems">Reporting Problems</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#architecture_support" role="button" aria-expanded="false" aria-controls="collapseExample">
        Architecture Support
      </a>
      <div class="collapse " id="architecture_support">
        
          <a class="subitem " href="/documentation/general_docs/architecture_support/">Architecture Support</a>
        
          <a class="subitem " href="/documentation/general_docs/architecture_support/arm_implementation/">ARM Implementation</a>
        
          <a class="subitem " href="/documentation/general_docs/architecture_support/isa_parser/">ISA Parser</a>
        
          <a class="subitem " href="/documentation/general_docs/architecture_support/x86_microop_isa/">X86 microop ISA</a>
        
      </div>
    
      <a class="item" href="/documentation/general_docs/thermal_model" role="button" aria-expanded="false" aria-controls="collapseExample">
        Power and Thermal Model
      </a>
      <div class="collapse " id="">
        
      </div>
    
      <a class="item" href="/documentation/general_docs/compiling_workloads/" role="button" aria-expanded="false" aria-controls="collapseExample">
        Compiling Workloads
      </a>
      <div class="collapse " id="compiling_workloads">
        
      </div>
    
      <a class="item" href="/documentation/general_docs/statistics/" role="button" aria-expanded="false" aria-controls="collapseExample">
        Stats Package
      </a>
      <div class="collapse " id="statistics">
        
      </div>
    
    
  
    
  
    
  
    
  
</div>


<div class="container" id="doc-container">
  <div class="edit"><a href="https://gem5.googlesource.com/public/gem5-website/+/refs/heads/master/README.md">Edit this page</a></div>
  
  

  <br>
  <h1 id="coding-style">Coding Style</h1>

<p>We strive to maintain a consistent coding style in the M5 source code to make the source more readable and maintainable. This necessarily involves compromise among the multiple developers who work on this code. We feel that we have been successful in finding such a compromise, as each of the primary M5 developers is annoyed by at least one of the rules below. We ask that you abide by these guidelines as well if you develop code that you would like to contribute back to M5. An Emacs c++-mode style embodying the indentation rules is available in the source tree at util/emacs/m5-c-style.el.</p>

<h2 id="indentation-and-line-breaks">Indentation and Line Breaks</h2>

<p>Indentation will be 4 spaces per level, though namespaces should not increase the indentation.</p>

<ul>
  <li>Exception: labels followed by colons (case and goto labels and public/private/protected modifiers) are indented two spaces from the enclosing context.</li>
</ul>

<p>Indentation should use spaces only (no tabs), as tab widths are not always set consistently, and tabs make output harder to read when used with tools such as diff.</p>

<p>Lines must be a maximum of 79 characters long.</p>

<h2 id="braces">Braces</h2>

<p>For control blocks (if, while, etc.), opening braces must be on the same line as the control keyword with a space between the closing parenthesis and the opening brace.</p>

<ul>
  <li>Exception: for multi-line expressions, the opening brace may be placed on a separate line to distinguish the control block from the statements inside the block.</li>
</ul>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="p">(...)</span> <span class="p">{</span>
    <span class="p">...</span>
<span class="p">}</span>

<span class="c1">// exception case</span>
<span class="k">for</span> <span class="p">(...;</span>
     <span class="p">...;</span>
     <span class="p">...)</span> <span class="c1">// brace could be up here</span>
<span class="p">{</span> <span class="c1">// but this is optionally OK *only* when the 'for' spans multiple lines</span>
    <span class="p">...</span>
<span class="p">}</span>
</code></pre></div></div>

<p>‘Else’ keywords should follow the closing ‘if’ brace on the same line, as follows:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="p">(...)</span> <span class="p">{</span>
    <span class="p">...</span>
<span class="p">}</span> <span class="k">else</span> <span class="nf">if</span> <span class="p">(...)</span> <span class="p">{</span>
    <span class="p">...</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
    <span class="p">...</span>
<span class="p">}</span>
</code></pre></div></div>

<p>Blocks that consist of a single statement that fits on a single line may optionally omit the braces. Braces are still required if the single statement spans multiple lines, or if the block is part of an else/if chain where other blocks have braces.</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// This is OK with or without braces</span>
<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span>
    <span class="o">--</span><span class="n">a</span><span class="p">;</span>

<span class="c1">// In the following cases, braces are still required</span>
<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
    <span class="n">obnoxiously_named_function_with_lots_of_args</span><span class="p">(</span><span class="n">verbose_arg1</span><span class="p">,</span>
                                                 <span class="n">verbose_arg2</span><span class="p">,</span>
                                                 <span class="n">verbose_arg3</span><span class="p">);</span>
<span class="p">}</span>

<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
    <span class="o">--</span><span class="n">a</span><span class="p">;</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
    <span class="n">underflow</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
    <span class="n">warn</span><span class="p">(</span><span class="s">"underflow on a"</span><span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>

<p>For function definitions or class declarations, the opening brace must be in the first column of the following line.</p>

<p>In function definitions, the return type should be on one line, followed by the function name, left-justified, on the next line. As mentioned above, the opening brace should also be on a separate line following the function name.</p>

<p>See examples below:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">int</span>
<span class="nf">exampleFunc</span><span class="p">(...)</span>
<span class="p">{</span>
    <span class="p">...</span>
<span class="p">}</span>

<span class="k">class</span> <span class="nc">ExampleClass</span>
<span class="p">{</span>
  <span class="nl">public:</span>
    <span class="p">...</span>
<span class="p">};</span>
</code></pre></div></div>

<p>Functions should be preceded by a block comment describing the function.</p>

<p>Inline function declarations longer than one line should not be placed inside class declarations. Most functions longer than one line should not be inline anyway.</p>

<h2 id="spacing">Spacing</h2>

<p>There should be:</p>

<ul>
  <li>one space between keywords (if, for, while, etc.) and opening parentheses</li>
  <li>one space around binary operators (+, -, &lt;, &gt;, etc.) including assignment operators (=, +=, etc.)</li>
  <li>no space around ‘=’ when used in parameter/argument lists, either to bind default parameter values (in Python or C++) or to bind keyword arguments (in Python)</li>
  <li>no space between function names and opening parentheses for arguments</li>
  <li>no space immediately inside parentheses, except for very complex expressions. Complex expressions are preferentially broken into multiple simpler expressions using temporary variables.</li>
</ul>

<p>For pointer and reference argument declarations, either of the following are acceptable:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">FooType</span> <span class="o">*</span><span class="n">fooPtr</span><span class="p">;</span>
<span class="n">FooType</span> <span class="o">&amp;</span><span class="n">fooRef</span><span class="p">;</span>
</code></pre></div></div>

<p>or</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">FooType</span><span class="o">*</span> <span class="n">fooPtr</span><span class="p">;</span>
<span class="n">FooType</span><span class="o">&amp;</span> <span class="n">fooRef</span><span class="p">;</span>
</code></pre></div></div>
<p>However, style should be kept consistent within a file. If you are editing an existing file, please keep consistent with the existing code. If you are writing new code in a new file, feel free to choose the style of your preference.</p>

<h2 id="naming">Naming</h2>

<p>Class and type names are mixed case, start with an uppercase letter, and do not contain underscores (e.g., ClassName). Exception: names that are acronyms should be all upper case (e.g., CPU). Class member names (method and variables, including const variables) are mixed case, start with a lowercase letter, and do not contain underscores (e.g., aMemberVariable). Class members that have accessor methods should have a leading underscore to indicate that the user should be using an accessor. The accessor functions themselves should have the same name as the variable without the leading underscore.</p>

<p>Local variables are lower case, with underscores separating words (e.g., local_variable). Function parameters should use underscores and be lower case.</p>

<p>C preprocessor symbols (constants and macros) should be all caps with underscores. However, these are deprecated, and should be replaced with const variables and inline functions, respectively, wherever possible.</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">FooBarCPU</span>
<span class="p">{</span>
  <span class="nl">private:</span>
    <span class="k">static</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">minLegalFoo</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span>  <span class="c1">// consts are formatted just like other vars</span>
    <span class="kt">int</span> <span class="n">_fooVariable</span><span class="p">;</span>   <span class="c1">// starts with '_' because it has public accessor functions</span>
    <span class="kt">int</span> <span class="n">barVariable</span><span class="p">;</span>    <span class="c1">// no '_' since it's internal use only</span>

  <span class="nl">public:</span>
    <span class="c1">// short inline methods can go all on one line</span>
    <span class="kt">int</span> <span class="n">fooVariable</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">_fooVariable</span><span class="p">;</span> <span class="p">}</span>

    <span class="c1">// longer inline methods should be formatted like regular functions,</span>
    <span class="c1">// but indented</span>
    <span class="kt">void</span>
    <span class="n">fooVariable</span><span class="p">(</span><span class="kt">int</span> <span class="n">new_value</span><span class="p">)</span>
    <span class="p">{</span>
        <span class="n">assert</span><span class="p">(</span><span class="n">new_value</span> <span class="o">&gt;=</span> <span class="n">minLegalFoo</span><span class="p">);</span>
        <span class="n">_fooVariable</span> <span class="o">=</span> <span class="n">new_value</span><span class="p">;</span>
    <span class="p">}</span>
<span class="p">};</span>
</code></pre></div></div>

<h2 id="includes">#includes</h2>

<p>Whenever possible favor C++ includes over C include. E.g. choose cstdio, not stdio.h.</p>

<p>The block of #includes at the top of the file should be organized. We keep several sorted groups. This makes it easy to find #include and to avoid duplicate #includes.</p>

<p>Always include Python.h first if you need that header. This is mandated by the integration guide. The next header file should be your main header file (e.g., for foo.cc you’d include foo.hh first). Having this header first ensures that it is independent and can be included in other places without missing dependencies.</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Include Python.h first if you need it.</span>
<span class="cp">#include &lt;Python.h&gt;
</span>
<span class="c1">// Include your main header file before any other non-Python headers (i.e., the one with the same name as your cc source file)</span>
<span class="cp">#include "main_header.hh"
</span>
<span class="c1">// C includes in sorted order</span>
<span class="cp">#include &lt;fcntl.h&gt;
#include &lt;sys/time.h&gt;
</span>
<span class="c1">// C++ includes</span>
<span class="cp">#include &lt;cerrno&gt;
#include &lt;cstdio&gt;
#include &lt;string&gt;
#include &lt;vector&gt;
</span>
<span class="c1">// Shared headers living in include/. These are used both in the simulator and utilities such as the m5 tool.</span>
<span class="cp">#include &lt;gem5/asm/generic/m5ops.h&gt;
</span>
<span class="c1">// M5 includes</span>
<span class="cp">#include "base/misc.hh"
#include "cpu/base.hh"
#include "params/BaseCPU.hh"
#include "sim/system.hh"
</span></code></pre></div></div>

<h2 id="file-structure-and-modularity">File structure and modularity</h2>

<p>Source files (.cc files) should never contain extern declarations; instead, include the header file associated with the .cc file in which the object is defined. This header file should contain extern declarations for all objects exported from that .cc file. This header should also be included in the defining .cc file. The key here is that we have a single external declaration in the .hh file that the compiler will automatically check for consistency with the .cc file. (This isn’t as important in C++ as it was in C, since linker name mangling will now catch these errors, but it’s still a good idea.)</p>

<p>When sufficient (i.e., when declaring only pointers or references to a class), header files should use forward class declarations instead of including full header files.</p>

<p>Header files should never contain using namespace declarations at the top level. This forces all the names in that namespace into the global namespace of any source file including that header file, which basically completely defeats the point of using namespaces. It is OK to use using namespace declarations at the top level of a source (.cc) file since the effect is entirely local to that .cc file. It’s also OK to use them in _impl.hh files, since for practical purposes these are source (not header) files despite their extension.</p>

<h2 id="documenting-the-code">Documenting the code</h2>

<p>Each file/class/member should be documented using doxygen style comments.Doxygen allows users to quickly create documentation for our code by extracting the relavent information from the code and comments. It is able to document all the code structures including classes, namespaces, files, members, defines, etc. Most of these are quite simple to document, you only need to place a special documentation block before the declaration. The Doxygen documentation within gem5 is processed every night and the following web pages are generated: <a href="https://gem5.github.io/gem5-doxygen/">Doxygen</a></p>

<h3 id="using-doxygen">Using Doxygen</h3>

<p>The special documentation blocks take the form of a javadoc style comment. A javadoc comment is a C style comment with 2 *’s at the start, like this:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/**
 * ...documentation...
 */</span>
</code></pre></div></div>

<p>The intermediate asterisks are optional, but please use them to clearly delineate the documentation comments.</p>

<p>The documentation within these blocks is made up of at least a brief description of the documented structure, that can be followed by a more detailed description and other documentation. The brief description is the first sentence of the comment. It ends with a period followed by white space or a new line. For example:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/**
 * This is the brief description. This is the start of the detailed
 * description. Detailed Description continued.
 */</span>
</code></pre></div></div>

<p>If you need to have a period in the brief description, follow it with a backslash followed by a space.</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/**
 * e.g.\ This is a brief description with an internal period.
 */</span>
</code></pre></div></div>
<p>Blank lines within these comments are interpreted as paragraph breaks to help you make the documentation more readble.</p>

<h3 id="special-commands">Special commands</h3>

<p>Placing these comments before the declaration works in most cases. For files however, you need to specify that you are documenting the file. To do this you use the @file special command. To document the file that you are currently in you just need to use the command followed by your comments. To comment a separate file (we shouldn’t have to do this) you can supply the name directly after the file command. There are some other special commands we will be using quite often. To document functions we will use @param and @return or @retval to document the parameters and the return value. @param takes the name of the paramter and its description. @return just describes the return value, while @retval adds a name to it. To specify pre and post conditions you can use @pre and @post.</p>

<p>Some other useful commands are @todo and @sa. @todo allows you to place reminders of things to fix/implement and associate them with a specific class or member/function. @sa lets you place references to another piece of documentation (class, member, etc.). This can be useful to provide links to code that would be helpful in understanding the code being documented.</p>

<h3 id="example-of-simple-documentation">Example of Simple Documentation</h3>

<p>Here is a simple header file with doxygen comments added.</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/**
 * @file
 * Contains an example of documentation style.
 */</span>

<span class="cp">#include &lt;vector&gt;
</span>
<span class="cm">/**
 * Adds two numbers together.
 */</span>
<span class="cp">#define DUMMY(a,b) (a+b)
</span>
<span class="cm">/**
 * A simple class description. This class does really great things in detail.
 *
 * @todo Update to new statistics model.
 */</span>
<span class="k">class</span> <span class="nc">foo</span>
<span class="p">{</span>
  <span class="cm">/** This variable stores blah, which does foo and has invariants x,y,z
         @warning never set this to 0
         @invariant foo
    */</span>
   <span class="kt">int</span> <span class="n">myVar</span><span class="p">;</span>

 <span class="cm">/**
  * This function does something.
  * @param a The number of times to do it.
  * @param b The thing to do it to.
  * @return The number of times it was done.
  *
  * @sa DUMMY
  */</span>
 <span class="kt">int</span> <span class="n">bar</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">long</span> <span class="n">b</span><span class="p">);</span>


 <span class="cm">/**
  * A function that does bar.
  * @retval true if there is a problem, false otherwise.
  */</span>
 <span class="kt">bool</span> <span class="n">manchu</span><span class="p">();</span>

<span class="p">};</span>
</code></pre></div></div>

<h3 id="grouping">Grouping</h3>

<p>Doxygen also allows for groups of classes and member (or other groups) to be declared. We can use these to create a listing of all statistics/global variables. Or just to comment about the memory hierarchy as a whole. You define a group using @defgroup and then add to it using @ingroup or @addgroup. For example:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/**
 * @defgroup statistics Statistics group
 */</span>

<span class="cm">/**
  * @defgroup substat1 Statistitics subgroup
  * @ingroup statistics
  */</span>

<span class="cm">/**
 *  A simple class.
 */</span>
<span class="k">class</span> <span class="nc">foo</span>
<span class="p">{</span>
  <span class="cm">/**
   * Collects data about blah.
   * @ingroup statistics
   */</span>
  <span class="n">Stat</span> <span class="n">stat1</span><span class="p">;</span>

  <span class="cm">/**
   * Collects data about the rate of blah.
   * @ingroup statistics
   */</span>
  <span class="n">Stat</span> <span class="n">stat2</span><span class="p">;</span>

  <span class="cm">/**
   * Collects data about flotsam.
   * @ingroup statistics
   */</span>
  <span class="n">Stat</span> <span class="n">stat3</span><span class="p">;</span>

  <span class="cm">/**
   * Collects data about jetsam.
   * @ingroup substat1
   */</span>
  <span class="n">Stat</span> <span class="n">stat4</span><span class="p">;</span>

<span class="p">};</span>
</code></pre></div></div>

<p>This places stat1-3 in the statistics group and stat4 in the subgroup. There is a shorthand method to place objects in groups. You can use @{ and @} to mark the start and end of group inclusion. The example above can be rewritten as:</p>

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/**
 * @defgroup statistics Statistics group
 */</span>

<span class="cm">/**
  * @defgroup substat1 Statistitics subgroup
  * @ingroup statistics
  */</span>

<span class="cm">/**
 *  A simple class.
 */</span>
<span class="k">class</span> <span class="nc">foo</span>
<span class="p">{</span>
  <span class="cm">/**
   * @ingroup statistics
   * @{
   */</span>

  <span class="cm">/** Collects data about blah.*/</span>
  <span class="n">Stat</span> <span class="n">stat1</span><span class="p">;</span>
  <span class="cm">/** Collects data about the rate of blah. */</span>
  <span class="n">Stat</span> <span class="n">stat2</span><span class="p">;</span>
  <span class="cm">/** Collects data about flotsam.*/</span>
  <span class="n">Stat</span> <span class="n">stat3</span><span class="p">;</span>

  <span class="cm">/** @} */</span>

  <span class="cm">/**
   * Collects data about jetsam.
   * @ingroup substat1
   */</span>
  <span class="n">Stat</span> <span class="n">stat4</span><span class="p">;</span>

<span class="p">};</span>
</code></pre></div></div>

<p>It remains to be seen what groups we can come up with.</p>

<h3 id="other-features">Other features</h3>

<p>Not sure what other doxygen features we want to use.</p>

<h2 id="m5-status-messages">M5 Status Messages</h2>
<h3 id="fatal-v-panic">Fatal v. Panic</h3>

<p>There are two error functions defined in <code class="highlighter-rouge">src/base/misc.hh:</code> <code class="highlighter-rouge">panic()</code> and <code class="highlighter-rouge">fatal()</code>. While these two functions have roughly similar effects (printing an error message and terminating the simulation process), they have distinct purposes and use cases. The distinction is documented in the comments in the header file, but is repeated here for convenience because people often get confused and use the wrong one.</p>

<ul>
  <li><code class="highlighter-rouge">panic()</code> should be called when something happens that should never ever happen regardless of what the user does (i.e., an actual m5 bug). <code class="highlighter-rouge">panic()</code> calls <code class="highlighter-rouge">abort()</code> which can dump core or enter the debugger.</li>
  <li><code class="highlighter-rouge">fatal()</code> should be called when the simulation cannot continue due to some condition that is the user’s fault (bad configuration, invalid arguments, etc.) and not a simulator bug. <code class="highlighter-rouge">fatal()</code> calls <code class="highlighter-rouge">exit(1)</code>, i.e., a “normal” exit with an error code.</li>
</ul>

<p>The reasoning behind these definitions is that there’s no need to panic if it’s just a silly user error; we only panic if m5 itself is broken. On the other hand, it’s not hard for users to make errors that are fatal, that is, errors that are serious enough that the m5 process cannot continue.</p>
<h3 id="inform-warn-and-hack">Inform, Warn and Hack</h3>

<p>The file <code class="highlighter-rouge">src/base/misc.hh</code> also houses 3 functions that alert the user to various conditions happening within the simulation: <code class="highlighter-rouge">inform()</code>, <code class="highlighter-rouge">warn()</code> and <code class="highlighter-rouge">hack()</code>. The purpose of these functions is strictly to provide simulation status to the user so none of these functions will stop the simulator from running.</p>

<ul>
  <li>
    <p><code class="highlighter-rouge">inform()</code> and <code class="highlighter-rouge">inform_once()</code> should be called for informative messages that users should know, but not worry about. <code class="highlighter-rouge">inform_once()</code> will only display the status message generated by the <code class="highlighter-rouge">inform_once()</code> function the first time it is called.</p>
  </li>
  <li>
    <p><code class="highlighter-rouge">warn()</code> and <code class="highlighter-rouge">warn_once()</code> should be called when some functionality isn’t necessarily implemented correctly, but it might work well enough. The idea behind a <code class="highlighter-rouge">warn()</code> is to inform the user that if they see some strange behavior shortly after a <code class="highlighter-rouge">warn()</code> the description might be a good place to go looking for an error.</p>
  </li>
  <li><code class="highlighter-rouge">hack()</code> should be called when some functionality isn’t implemented nearly as well as it could or should be but for expediency or history sake hasn’t been fixed.</li>
  <li><code class="highlighter-rouge">inform()</code> Provides status messages and normal operating messages to the console for the user to see, without any connotations of incorrect behavior. For example it’s used when secondary CPUs being executing code on ALPHA.</li>
</ul>

  <br>

  <!-- RETRIVE PREVIOUS PAGE LINK -->
  
    
  
    
  
    
  
    
  

  <!-- RETRIEVE NEXT PAGE LINK -->
  
    
  
    
  
    
  
    
  


  <div class="navbuttons">
    
      <a href=""><button type="button" class="btn btn-outline-primary">PREVIOUS</button></a>
    

    
      <a href=""><button type="button" class="btn btn-outline-primary">NEXT</button></a>
    
  </div>
</div>

	</main>
	<footer class="page-footer">
	<div class="container">
		<div class="row">

			<div class="col-12 col-sm-4">
				<p>gem5</p>
				<p><a href="/about">About</a></p>
				<p><a href="/publications">Publications</a></p>
				<p><a href="/contributing">Contributing</a></p>
				<p><a href="/governance">Governance</a></p>
			<br></div>

			<div class="col-12 col-sm-4">
				<p>Docs</p>
				<p><a href="/documentation">Documentation</a></p>
				<p><a href="http://gem5.org/Documentation">Old Documentation</a></p>
				<p><a href="https://gem5.googlesource.com/public/gem5">Source</a></p>
			<br></div>

			<div class="col-12 col-sm-4">
				<p>Help</p>
				<p><a href="/search">Search</a></p>
				<p><a href="/mailing_lists">Mailing Lists</a></p>
				<p><a href="https://gem5.googlesource.com/public/gem5-website/+/refs/heads/master/README.md">Website Source</a></p>
			<br></div>

		</div>
	</div>
</footer>


	<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
	<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
	<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
	<script src="https://unpkg.com/commentbox.io/dist/commentBox.min.js"></script>

	<script>
	  // When the user scrolls down 20px from the top of the document, show the button
	  window.onscroll = function() {scrollFunction()};

	  function scrollFunction() {
	      if (document.body.scrollTop > 100 || document.documentElement.scrollTop > 20) {
	          document.getElementById("myBtn").style.display = "block";
	      } else {
	          document.getElementById("myBtn").style.display = "none";
	      }
	  }

	  // When the user clicks on the button, scroll to the top of the document
	  function topFunction() {
	      document.body.scrollTop = 0;
	      document.documentElement.scrollTop = 0;
	  }

		import commentBox from 'commentbox.io';
		// or
		const commentBox = require('commentbox.io');
		// or if using the CDN, it will be available as a global "commentBox" variable.

		commentBox('my-project-id');

	</script>

</body>


</html>
